package com.magenta.maxoptra.gis;


import com.magenta.maxoptra.dto.GeoLocationRecord;

import java.util.List;

/*
* Interface IGeoRoute ...
* <b>WARNING!!!</b> Low-level interface for simple queries and without caching.
*
* Project: MaxOptRA v1.1
* User: Ivan Usalko
* Date: 19.01.2009 12:47:17
*
* Copyright (c) 1999-2009 Magenta Corporation Ltd. All Rights Reserved.
* Magenta Technology proprietary and confidential.
* Use is subject to license terms.
*/
public interface IGeoRouting extends IGeoProvider {

    /**
     * Request fastest route from source "<code>from</code>" to destination "<code>to</code>".
     *
     * @param from source location
     * @param to   destination location
     * @return route info.
     * @throws GeoException throw if getting process failed or server return bad response.
     */
    GeoRoute getRoute(GeographicCoordinates from, GeographicCoordinates to) throws GeoException, ServerUnavailableException;
    GeoRoute getRoute(GeographicCoordinates from, GeographicCoordinates to, VehicleType vehicleType) throws GeoException, ServerUnavailableException;

    GeoRoute getRoute(List<GeographicCoordinates> coordinates) throws GeoException;
    GeoRoute getRoute(List<GeographicCoordinates> coordinates, VehicleType vehicleType) throws GeoException;


    /**
     * Request list of time+destination for routes from "<code>from</code>" to destinations "<code>to</code>".
     *
     *
     * @param from source location
     * @param to   destination locations
     * @param timeout timeout for operation. Less that zero if the timeout is not needed
     * @return route info for each route
     * @throws GeoException throw if getting process failed or server return bad response.
     */
    List<GeoRoute> getRoute(GeographicCoordinates from, List<? extends GeographicCoordinates> to, int timeout) throws GeoException, ServerUnavailableException;
    List<GeoRoute> getRoute(GeographicCoordinates from, List<? extends GeographicCoordinates> to, VehicleType vehicleType, int timeout) throws GeoException, ServerUnavailableException;

    /**
     * Возвращает список точек маршрута, пролегающего между двумя указанными локациями
     *
     *
     * @param settings атрибуты, необходимые для работы метода
     * @param from исходная локация
     * @param to   локация назначение
     * @return список точер маршрута, пролегающего между двумя указанными локациями
     * @throws GeoException -
     */
    List<GeoLocationRecord> getRoutePoints(GeoProviderSettings settings, GeographicCoordinates from, GeographicCoordinates to) throws GeoException;

    /**
     * Возвращает список точек маршрута, пролегающего между указанными локациями
     *
     *
     * @param settings атрибуты, необходимые для работы метода
     * @param points локации
     * @return список точер маршрута, пролегающего между указанными локациями
     * @throws GeoException -
     */
    List<GeoLocationRecord> getRoutePoints(GeoProviderSettings settings, List<GeographicCoordinates> points) throws GeoException;

    /**
     * Request list of time+destination for routes from "<code>from</code>" to destinations "<code>to</code>".
     *
     *
     * @param from source location
     * @param to   destination locations
     * @param timeout timeout for operation. Less that zero if the timeout is not needed
     * @return route info for each route
     * @throws GeoException throw if getting process failed or server return bad response.
     */
    List<GeoRoute> getRoutes(GeographicCoordinates from, List<? extends GeographicCoordinates> to, int timeout) throws GeoException, ServerUnavailableException;
    List<GeoRoute> getRoutes(GeographicCoordinates from, List<? extends GeographicCoordinates> to, VehicleType vehicleType, int timeout) throws GeoException, ServerUnavailableException;

    /**
     * Getting distance and trip duration going through all points in order in which they are listed
     *
     * @param coordinates list of stops
     * @return calculated distance and duration
     */
    List<GeoRoute> getCoordinateToCoordinateRoutes(List<GeographicCoordinates> coordinates) throws ServerUnavailableException;
}
